Skip to main content

About Connections

Common Parameters​

The following table lists the properties applicable to all connections:

PropertyConfiguration Value
active (optional, default=true)- Enables or disables the connection.
- When set to false, the connection stops within 1 minute if previously active.
connectorId (mandatory)Defines the type of connector to use, e.g., actility-aws-iot or actility-azure-iot.
name (mandatory)Name of the connection (for informational purposes).
alarms (optional)Defines alarms for low flow rates. See the section below for more details.
configuration (mandatory)- Defines all specific parameters of the connection.
- Properties vary depending on the connector type. Refer to the specific chapter for each connector for details.
configuration/description (optional)Optional description text for the configuration.
configuration/createDevices (optional, default=true)- If set to true, the connection attempts to auto-register devices on the cloud upon receiving the first uplink message (if not already created).
- If set to false and a device is not found, the uplink is skipped.
configuration/sendMetadata (optional)- For backward compatibility, setting this to true removes the DevEUI_uplink root node in uplinks.
- Only uplink messages are received; downlink acknowledgments are filtered.
- Default value: false.
configuration/sendRawDecodedFormat (optional, default=false)- If sendMetadata is false and sendRawDecodedFormat is true, only the payload field content is sent to the cloud.
- If payload is absent, the entire uplink message body is sent.
configuration/uplinkTimeValidity (optional)- Sets the validity period for uplinks (e.g., 1m for 1 minute).
- Uplinks older than the specified value are skipped, and an alarm event is logged.
- Useful for preventing outdated messages after downtimes.
configuration/downlinkEnabled (default=true)- Enables or disables downstream messaging.
- Set to false to disable downstream capabilities.
configuration/downlinkAsIdSpecifies the authentication AS_ID value for downlinks requiring authentication.
configuration/downlinkAsKeySpecifies the authentication AS_KEY value for downlinks requiring authentication.
configuration/downlinkPort (optional)Sets the default port for downlink messages when no port is specified.
configuration/reconnectStrategy (optional, default=NORMAL)Defines the reconnect strategy when a connection fails to reach the OPENED state. Options:
- CALM: Retries every 10 minutes for 12 hours, then hourly for 1 day.
- NORMAL: Retries every 5 minutes for 1 hour, then hourly for 1 day.
- AGGRESSIVE: Retries every 3 minutes for 3 hours, then every 30 minutes for 1 week, followed by hourly retries indefinitely.

Reconnection strategy​

Each connector follow a reconnection strategy when it failed and close. This setup could be set only using API and the field configuration/reconnectStrategy (default=NORMAL). Options are :

  • CALM: Retries every 10 minutes for 12 hours, then hourly for 1 day.
  • NORMAL: Retries every 5 minutes for 1 hour, then hourly for 1 day.
  • AGGRESSIVE: Retries every 3 minutes for 3 hours, then every 30 minutes for 1 week, followed by hourly retries indefinitely.

Topic Pattern Expression​

Some connection configuration fields, like uplinkTopicPattern, accept JsonPath expressions. Expressions defined within {} can reference fields in the uplink message. A fallback can be set using the | operator.

For example, given the uplink message, these expressions generate topics:

  • mqtt/thing/{DevEUI}/uplink → mqtt/thing/0018B20000000BEE/uplink
  • mqtt/thing/{DevEUI}/{FPort}/uplink → mqtt/thing/0018B20000000BEE/1/uplink
  • mqtt/thing/{DevEUI|'None'}/uplink → mqtt/thing/0018B20000000BEE/uplink (Fallback: None if DevEUI is missing)
  • mqtt/thing/{CustomerData.name|DevEUI|deviceEUI|'None'}/uplink → mqtt/thing/Adeunis_FieldTester_Bruno/uplink (# is replaced by _ automatically)
Note
  • In MQTT connectors, if the resolved topic contains # or +, it is automatically replaced with _.
  • Complex JsonPath expressions like mqtt/thing/{$..CustomerData.tags[?(@ =~ /Site=.*/)]}/uplink can be optimized to mqtt/thing/{tags='Site=.*'}/uplink for better efficiency.

For more information:

Connection States​

The state of a connection reflects its current lifecycle. Due to the asynchronous architecture, an action like starting may not immediately change the state.

Connection StateDescription
OPENINGThe connection is currently opening.
OPENEDThe connection is active and operational.
CLOSEDThe connection is closing.
AUTHENTICATINGThe connection is undergoing authentication.
AUTHENTICATION_FAILEDAuthentication failed.
UNREACHABLEThe bridge hosting the connection is unreachable, and no information is retrievable.
DEACTIVATEDThe connection is currently deactivated.

The connection workflow is illustrated in the following diagram:

Connection Workflow

Last updated on